Arthas线上故障排查实战手册

# 下载 arthas-boot.jar
curl -O https://arthas.aliyun.com/arthas-boot.jar

# 启动（会列出当前机器上的 Java 进程，选择要诊断的进程）
java -jar arthas-boot.jar

[INFO] arthas-boot version: 4.x.x
[INFO] Found existing java process, please choose one and input the serial number:
* [1]: 12345 com.example.MyApplication
  [2]: 23456 org.apache.catalina.startup.Bootstrap

# 通过 PID 指定
java -jar arthas-boot.jar 12345

# 通过进程名指定（推荐，因为 PID 每次重启会变）
java -jar arthas-boot.jar --select MyApplication

# 方式一：进入容器后执行
docker exec -it <container_id> /bin/bash
java -jar arthas-boot.jar

# 方式二：使用 docker exec 直接运行（需容器内已有 JDK）
docker exec -it <container_id> java -jar /path/to/arthas-boot.jar

<dependency>
    <groupId>com.taobao.arthas</groupId>
    <artifactId>arthas-spring-boot-starter</artifactId>
    <version>4.x.x</version>
    <scope>provided</scope>
</dependency>

# 退出当前 Arthas 会话（不影响应用运行）
quit
# 或
exit

# 彻底卸载 Arthas（清理增强的字节码）
stop

dashboard（全局概览）
    │
    ├─ CPU 高 → thread -n <N>（找最忙线程）→ thread <id>（看堆栈）→ jad（反编译确认）→ trace/watch（定位具体方法）
    │
    ├─ 接口慢 → trace（追踪耗时链路）→ watch（观测入参出参）→ 找到瓶颈节点
    │
    ├─ 异常报错 → watch（观测异常）→ stack（看调用来源）→ jad（确认代码逻辑）
    │
    ├─ 内存/OOM → dashboard（看内存区域）→ vmtool（查堆内对象）→ heapdump（导出堆）
    │
    └─ 类加载问题 → sc（查类是否加载）→ jad（反编译看版本）→ dump（导出字节码比对）

[arthas@12345]$ dashboard

# 查看占用 CPU 最高的 3 个线程
[arthas@12345]$ thread -n 3

threads name                  cpu      state
pool-1-thread-1               85.6%    RUNNABLE
http-nio-8080-exec-3          8.2%     RUNNABLE
GC thread                     4.1%     RUNNABLE

# 查看指定线程的完整堆栈
[arthas@12345]$ thread 1

"pool-1-thread-1" Id=32 cpu=85.6% RUNNABLE
    at com.example.service.OrderService.calculatePrice(OrderService.java:128)
    at com.example.service.OrderService.processOrder(OrderService.java:95)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)

# 反编译确认运行中的代码逻辑
[arthas@12345]$ jad com.example.service.OrderService calculatePrice

# 追踪该方法内部调用，观察是否一直在循环
[arthas@12345]$ trace com.example.service.OrderService calculatePrice -n 5 --skipJDKMethod false

[arthas@12345]$ trace com.example.controller.OrderController queryOrder -n 5

`---[3205ms] com.example.controller.OrderController:queryOrder()
    +---[0.15ms] com.example.dto.OrderRequest:validate()
    +---[3012ms] com.example.service.OrderService:getOrder()
    |   `---[2980ms] com.example.mapper.OrderMapper:selectById()
    |       `---[2975ms] org.apache.ibatis.session.SqlSession:selectOne()
    +---[180ms] com.example.service.PriceService:calculatePrice()
    `---[12ms] com.example.converter.OrderConverter:toVO()

# 观察方法入参，展开 2 层
[arthas@12345]$ watch com.example.mapper.OrderMapper selectById "{params, returnObj}" -x 2

method=com.example.mapper.OrderMapper.selectById params=[null]

# 追踪 OrderService 中传入 mapper 的值来源
[arthas@12345]$ trace com.example.service.OrderService getOrder -n 3

# 只追踪耗时超过 500ms 的调用
[arthas@12345]$ trace com.example.controller.OrderController queryOrder '#cost > 500' -n 5

trace <class-pattern> <method-pattern> [条件表达式] [参数]

#cost          方法执行耗时（毫秒），可用于条件过滤
-n <N>         最多匹配次数，达到后自动停止（重要，避免持续增强）
--skipJDKMethod <true|false>  是否跳过 JDK 方法（默认 true）
-x <N>         展开层级（对 trace 不常用，主要用于 watch）
-v             打印条件表达式的执行结果

# 观测入参和抛出的异常，展开 3 层
[arthas@12345]$ watch com.example.service.CouponService apply "{params, throwExp}" -x 3

method=com.example.service.CouponService.apply params=[CouponRequest(userId=12345, couponId=null, amount=100.0)]
throwExp=java.lang.NullPointerException: Cannot invoke "Coupon.getType()" because "coupon" is null

# 只在抛出异常时输出
[arthas@12345]$ watch com.example.service.CouponService apply "{params, throwExp}" "#throwExp != null" -x 3

# 查看是谁调用了 apply 方法
[arthas@12345]$ stack com.example.service.CouponService apply -n 3

ts=2026-07-15 10:30:45; thread_name=http-nio-8080-exec-5; id=45; is_daemon=false; priority=5;
    @com.example.controller.OrderController.createOrder()
        at com.example.service.OrderService.processOrder(OrderService.java:89)
        at com.example.service.CouponService.apply(CouponService.java:70)

[arthas@12345]$ jad com.example.service.CouponService apply

watch <class-pattern> <method-pattern> <观察表达式> [条件表达式] [参数]

观察表达式中可用的内置变量：
  params       方法入参数组
  returnObj    方法返回值
  throwExp     方法抛出的异常
  target       方法所在对象实例
  #cost        方法执行耗时（ms）

常用参数：
  -x <N>       展开层级，-x 1 只显示一层，-x 3 展开三层嵌套对象
  -n <N>       匹配次数上限
  -b           在方法调用前观察（此时 returnObj 和 throwExp 为 null）
  -e           在方法抛出异常后观察
  -s           在方法返回后观察
  -f           在方法结束后观察（无论正常返回或异常，默认行为）

[arthas@12345]$ memory

Memory used     total      max      usage
heap   1.2G     2.0G       4.0G     30.42%
non_heap 256M   320M       -1       -
g1_eden 120M    160M       -1       75.00%
g1_old  1.0G    1.6G       4.0G     63.13%
g1_survivor 32M 48M        -1       66.67%

[arthas@12345]$ dashboard

# 查询堆中某个类的实例对象，限制 10 个
[arthas@12345]$ vmtool --action getInstances --className com.example.model.OrderCache --limit 10

# 查看实例被谁引用（找到 GC Root 引用链）
[arthas@12345]$ vmtool --action getInstances --className com.example.model.OrderCache --limit 1 --express 'instances[0]'

# 查询某个缓存类的实例
[arthas@12345]$ vmtool --action getInstances --className java.util.concurrent.ConcurrentHashMap --limit 1 \
  --express 'instances[0].size'

# 导出完整堆 dump
[arthas@12345]$ heapdump /tmp/heapdump.hprof

# 查看某个缓存管理类的静态字段
[arthas@12345]$ getstatic com.example.cache.OrderCacheManager cacheMap

[arthas@12345]$ logger

 name                                   level  classLoader    classLoaderHash
 ROOT                                   INFO   BootClassLoader 5a54a66
 com.example                            INFO   BootClassLoader 5a54a66
 com.example.service.OrderService       INFO   BootClassLoader 5a54a66
 org.springframework                    WARN   BootClassLoader 5a54a66
 org.mybatis                            DEBUG  BootClassLoader 5a54a66

# 修改指定包的日志级别
[arthas@12345]$ logger --name com.example --level DEBUG

# 只对某个类开启 DEBUG
[arthas@12345]$ logger --name com.example.service.OrderService --level DEBUG

# 恢复为 INFO
[arthas@12345]$ logger --name com.example --level INFO

# 通过 OGNL 直接调用 Logback API 修改级别
[arthas@12345]$ ognl '@org.slf4j.LoggerFactory@getLogger("com.example").setLevel(@ch.qos.logback.classic.Level@DEBUG)'

# 查找所有匹配的已加载类（支持通配符）
[arthas@12345]$ sc -d com.example.dto.OrderRequest

 class-info        com.example.dto.OrderRequest
 code-source       /data/app/lib/example-dto-1.2.0.jar
 name              com.example.dto.OrderRequest
 isInterface       false
 isAnnotation      false
 isEnum            false
 isAnonymousClass  false
 isArray           false
 isLocalClass      false
 isMemberClass     false
 isPrimitive       false
 isSynthetic       false
 simple-name       OrderRequest
 modifier          public
 annotation        
 interfaces        
 super-class       java.lang.Object
 class-loader      +-sun.misc.Launcher$AppClassLoader@5a54a66
                     +-sun.misc.Launcher$ExtClassLoader@1234abcd
 classLoaderHash   5a54a66

# 查看所有匹配的类（可能存在多个版本被不同 ClassLoader 加载）
[arthas@12345]$ sc -d *OrderRequest*

# 反编译查看实际运行的代码
[arthas@12345]$ jad com.example.dto.OrderRequest

# 导出运行中的字节码到文件
[arthas@12345]$ dump com.example.dto.OrderRequest -d /tmp/dump

# 查看所有类加载器
[arthas@12345]$ classloader

 name                                       loadedCount  hash        parent
 BootstrapClassLoader                       2845         null        null
 sun.misc.Launcher$ExtClassLoader           12           1234abcd    BootstrapClassLoader
 sun.misc.Launcher$AppClassLoader           3567         5a54a66     ExtClassLoader
 org.springframework.boot.loader.LaunchedURLClassLoader  2341  abcdef12  AppClassLoader

# 检测死锁（Arthas 会自动分析线程的锁等待关系）
[arthas@12345]$ thread -b

# 查看指定线程的堆栈
[arthas@12345]$ thread 45

"http-nio-8080-exec-3" Id=45 WAITING on java.util.concurrent.locks.ReentrantLock@3f5a2b1c owned by "http-nio-8080-exec-5" Id=47

    at java.lang.Object.wait(Native Method)
    - waiting on java.util.concurrent.locks.ReentrantLock@3f5a2b1c
    at com.example.service.InventoryService.deductStock(InventoryService.java:52)
    - locked java.util.concurrent.locks.ReentrantLock@7c8d9e0f <---- 但 blocks "http-nio-8080-exec-5"

# 查看所有状态为 BLOCKED 的线程
[arthas@12345]$ thread --state BLOCKED

# 反编译查看死锁涉及的代码
[arthas@12345]$ jad com.example.service.InventoryService deductStock

# 反编译并只输出源码
[arthas@12345]$ jad --source-only com.example.service.OrderService > /tmp/OrderService.java

# 使用 vim 或 sed 修改
vim /tmp/OrderService.java

# 编译修改后的 Java 文件
[arthas@12345]$ mc /tmp/OrderService.java -d /tmp/output

Memory compiler output:
/tmp/output/com/example/service/OrderService.class

# 加载新的 class 文件替换运行中的类
[arthas@12345]$ redefine /tmp/output/com/example/service/OrderService.class

# 用 watch 观察方法行为是否已变更
[arthas@12345]$ watch com.example.service.OrderService createOrder "{params, returnObj}" -x 2

# 先查看类的 ClassLoaderHash
[arthas@12345]$ sc -d com.example.service.OrderService | grep classLoaderHash
# classLoaderHash 5a54a66

# 编译时指定 ClassLoader
[arthas@12345]$ mc -c 5a54a66 /tmp/OrderService.java -d /tmp/output

# redefine 时也指定
[arthas@12345]$ redefine -c 5a54a66 /tmp/output/com/example/service/OrderService.class

# 查找连接池对象实例（以 HikariCP 为例）
[arthas@12345]$ vmtool --action getInstances --className com.zaxxer.hikari.HikariDataSource --limit 5

# 通过 OGNL 查看连接池的关键指标
[arthas@12345]$ ognl '#data = @com.zaxxer.hikari.HikariDataSource@class, \
  #instances = #data.getName(), \
  #pool = #data.getDeclaredField("pool"), \
  #pool.setAccessible(true), \
  #hikariPool = #pool.get(null), \
  #hikariPool.toString()' -c 5a54a66

# 查看连接池配置和当前状态
[arthas@12345]$ getstatic com.zaxxer.hikari.HikariPoolMXBean poolName
[arthas@12345]$ vmtool --action getInstances --className com.zaxxer.hikari.HikariPool --limit 1 \
  --express 'instances[0]'

# 追踪 getConnection 方法的耗时
[arthas@12345]$ trace com.zaxxer.hikari.HikariDataSource getConnection -n 5

# 观察数据库查询方法的执行时间
[arthas@12345]$ trace org.springframework.jdbc.core.JdbcTemplate query '#cost > 1000' -n 10

# 监控连接的借出和归还
[arthas@12345]$ watch com.zaxxer.hikari.pool.PoolEntry getConnection "{params, returnObj}" -x 1 -n 20

# 查看哪些线程在等待连接
[arthas@12345]$ thread --state WAITING | grep -i "getConnection\|Hikari"

# 只在 userId=12345 的调用时输出入参和返回值
[arthas@12345]$ watch com.example.service.OrderService createOrder \
  "{params, returnObj}" \
  "params[0].userId == 12345" \
  -x 3

# 条件追踪，只在特定用户调用时追踪耗时
[arthas@12345]$ trace com.example.service.OrderService createOrder \
  'params[0].userId == 12345' \
  -n 1

# 直接调用 Service 方法查询该用户数据（不影响业务，只读操作）
[arthas@12345]$ ognl '@com.example.SpringContextHolder@getBean(@com.example.service.UserDataService@class).getUserData(12345)' -x 3

# 通过 Spring ApplicationContext 获取 Bean 并调用方法
[arthas@12345]$ ognl '#context = @org.springframework.web.context.ContextLoader@getCurrentWebApplicationContext(), \
  #service = #context.getBean("userService"), \
  #service.getUserProfile(12345)' -x 3

# 记录方法所有调用
[arthas@12345]$ tt -t com.example.service.OrderService createOrder

# 查看所有记录
[arthas@12345]$ tt -l

# 查看某次调用的详细信息
[arthas@12345]$ tt -i 1000

# 重放某次调用（重新执行该方法，使用记录时的入参）
[arthas@12345]$ tt -i 1000 -p

tt -t <class> <method>     开始记录方法调用
tt -l                       列出所有记录
tt -i <index>               查看指定记录详情
tt -i <index> -p            重放指定记录
tt --delete <index>         删除指定记录
tt --delete-all             清除所有记录

# 1. 调用静态方法
ognl '@java.lang.System@getProperty("java.version")'

# 2. 获取 Spring Bean 并调用方法
ognl '#context = @org.springframework.web.context.ContextLoader@getCurrentWebApplicationContext(), #bean = #context.getBean("myService"), #bean.doSomething()'

# 3. 在 watch 中构造复杂条件
watch com.example.service.OrderService createOrder "{params, returnObj}" \
  "params[0].userId == 12345 && #cost > 500 && returnObj != null" -x 3

# 4. 在 watch 中调用方法处理参数
watch com.example.service.OrderService createOrder \
  "@com.example.JsonUtils@toJson(params[0])" -x 1

# 5. 获取方法执行时间并做条件判断
watch com.example.service.OrderService createOrder \
  "{params, #cost}" "#cost > 1000" -x 2

# 6. 获取目标对象的字段值
watch com.example.service.OrderService createOrder \
  "target.cacheMap.size" -x 1

# 在后台执行 watch 命令，加 & 表示后台运行
[arthas@12345]$ watch com.example.service.OrderService createOrder "{params, returnObj}" -x 2 &

# 查看后台任务
[arthas@12345]$ jobs

# 查看后台任务输出
[arthas@12345]$ jobs -d

# 停止后台任务
[arthas@12345]$ jobs -k <job_id>

# 启动时重定向输出到文件
[arthas@12345]$ watch com.example.service.OrderService createOrder "{params}" -x 2 >> /tmp/arthas-watch.log &

# 开始采集（默认采样 CPU）
[arthas@12345]$ profiler start

# 等待一段时间（30秒~几分钟）

# 停止采集并生成火焰图
[arthas@12345]$ profiler stop --format html

# 采集内存分配火焰图
[arthas@12345]$ profiler start --event alloc

# 采集指定时间后自动停止
[arthas@12345]$ profiler start --duration 60

# 创建命令文件
cat > /tmp/arthas-commands.txt << 'EOF'
dashboard -n 1
thread -n 5
sc -d com.example.service.OrderService
jad com.example.service.OrderService
EOF

# 批量执行
java -jar arthas-boot.jar 12345 -f /tmp/arthas-commands.txt

# 模拟"条件断点"：当订单金额大于 10000 且用户为 VIP 时才观测
watch com.example.service.OrderService createOrder \
  "{params, returnObj, target}" \
  "params[0].amount > 10000 && params[0].userLevel == 'VIP'" \
  -x 4 -n 1

# 查找类时指定 ClassLoaderHash
[arthas@12345]$ sc -d com.example.service.OrderService
# 输出中找到 classLoaderHash: 5a54a66

# 所有命令都可以通过 -c 指定 ClassLoader
[arthas@12345]$ watch -c 5a54a66 com.example.service.OrderService createOrder "{params}" -x 2
[arthas@12345]$ jad -c 5a54a66 com.example.service.OrderService
[arthas@12345]$ redefine -c 5a54a66 /tmp/OrderService.class

# 看全局
dashboard

# 找最忙线程
thread -n 3

# 看线程堆栈
thread <thread_id>

# 反编译确认代码
jad <class> <method>

# 追踪方法耗时
trace <class> <method> -n 5

# 观测入参出参
watch <class> <method> "{params, returnObj}" -x 3

# 查看日志级别
logger

# 改日志级别
logger --name <package> --level DEBUG

# 查看内存
memory

# 查堆内对象
vmtool --action getInstances --className <class> --limit 10

# 查看静态字段
getstatic <class> <field>

# 查看已加载类
sc -d <class>

# 执行 OGNL
ognl '<expression>'

# 热更新
jad --source-only <class> > /tmp/X.java  # 反编译
mc /tmp/X.java -d /tmp/output            # 编译
redefine /tmp/output/<path>/X.class      # 加载

# 火焰图
profiler start
profiler stop --format html

# 退出
quit        # 退出会话
stop        # 彻底卸载

#cost > 500                          # 耗时超过 500ms
params[0].userId == 12345            # 特定用户
#throwExp != null                    # 抛出异常时
returnObj == null                    # 返回值为 null
params[0].userId == 12345 && #cost > 500   # 组合条件