Skip to content

2.1-3 Java Agent:premain / agentmain、instrument ​

所属:02 Java 运行时 / 2.1 Java 基础 分级:B(按 A 类模板展开) 状态:◐ 初稿 关联:2.1-2、2.1-1、2.3-11、2.3-2、2.1-6

  • 题型:原理 / 场景

  • 一句话结论:Java Agent 是 JVM 暴露给 Java 层的字节码插桩入口:启动时用 -javaagent 走 premain(在 main 之前执行),运行期用 Attach API 走 agentmain;两者都拿到 Instrumentation,注册 ClassFileTransformer,在类被定义之前改写字节码,配合 retransformClasses 做已加载类的重转换。它不是“随便改代码”的魔法:只能改方法体,不能加字段、改签名、改继承,还要处理栈映射帧、类加载器、模块访问;APM、Arthas、Mock、JaCoCo、热修复都建在这套机制上。

  • 分层要点:

    1. 定位:JVM 的 JVMTI 是 C 层调试/监控接口,java.lang.instrument 是它在 Java 层的封装(JDK 5 引入)。Agent 是一段随目标 JVM 运行的代码,通过 Instrumentation 在类加载链路里插入自己,从而做监控、增强、Mock、热更新。
    2. 两种入口:startup agent 用 -javaagent:/path/agent.jar[=opts],JVM 在 main 前调用 premain(String args, Instrumentation inst);dynamic agent 先由外部进程 Attach 到目标 JVM,再调用 agentmain(String args, Instrumentation inst)。前者能覆盖几乎所有类(main 之前加载的都已插桩),后者只能从附加时刻之后的类加载开始生效,已加载的类要靠 retransform。
    3. premain 的装载条件:agent jar 的 META-INF/MANIFEST.MF 必须写 Premain-Class;需要重定义/重转换时写 Can-Redefine-Classes: true、Can-Retransform-Classes: true;Boot-Class-Path 可把依赖加进 bootstrap 搜索路径。premain 抛异常会导致 JVM 启动失败。
    4. agentmain 的装载条件:Manifest 写 Agent-Class;目标 JVM 必须开启 Attach 机制(HotSpot 默认开启,-XX:+DisableAttachMechanism 会关闭)。Attach 客户端(com.sun.tools.attach.VirtualMachine)通过 Unix domain socket(Linux 常见 /tmp/.java_pid<pid>)向目标 JVM 的 Attach Listener 线程发送 load 指令,目标 JVM 加载 agent jar 并回调 agentmain。要求同用户/有权限、同一 PID namespace(容器里 attach 要注意)。
    5. Instrumentation 能做什么:addTransformer(t, canRetransform) 注册转换器;retransformClasses(...) 对已加载类重跑转换;redefineClasses(...) 直接替换类定义;getAllLoadedClasses()、isModifiableClass()、getObjectSize()、appendToBootstrapClassLoaderSearch(JarFile)、appendToSystemClassLoaderSearch(JarFile)。Transformer 的返回值:null 表示不改,返回 byte[] 表示用新字节码替换。
    6. 字节码改写:主流用 ASM(访问者/树 API,性能最好、最底层)、ByteBuddy(API 友好,Arthas/Mockito/SkyWalking 常用)、Javassist(源码级 API,性能一般)、CGLib(已较少用于 agent)。改写方法体要做 try/finally、计时、异常捕获时,必须重算 StackMapTable(ASM ClassWriter.COMPUTE_FRAMES),否则 Java 7+ 校验器直接拒绝;而计算帧需要类型层次,getCommonSuperClass 用错类加载器会触发类加载甚至 ClassCircularityError。
    7. retransform 的边界:只能改方法体(以及常量池等),不能新增/删除字段或方法、不能改方法签名、不能改继承关系;redefineClasses 限制更严。retransform 的语义是从初始 classfile 重新应用所有 canRetransform=true 的 transformer,不是在上次结果上叠加;已经在栈上的方法帧继续执行旧版本,新调用才走新代码——所以“热修复”对正在执行的方法不是立即生效。isModifiableClass 为 false 的类(部分数组、基本类型、hidden class)不能改。
    8. 类加载器与模块:transformer 运行在类加载的关键路径上,不能在里面加载类(会递归触发 transform,导致死锁或 ClassCircularityError);被增强的类若引用 agent 的类,而 agent 不在其可见的类加载器里,会 NoClassDefFoundError,需要 appendToBootstrapClassLoaderSearch 或把依赖放进 bootstrap。JDK 9+ 模块化后,访问 java.base 的非导出包要 --add-opens;JDK 21 起动态加载 agent 会打印警告(JEP 451),需要 -XX:+EnableDynamicAgentLoading 才静默,未来版本可能默认禁止。
  • 图/流程:

text
premain(启动期):
  java -javaagent:agent.jar=opts -jar app.jar
    → JVM 解析 Manifest 的 Premain-Class
    → 加载 agent → 调用 premain(args, inst)
    → agent 注册 ClassFileTransformer
    → main 开始执行;此后每个类加载都经过 transformer
text
agentmain(运行期 Attach):
  外部进程                         目标 JVM
  VirtualMachine.attach(pid)
    → 通过 /tmp/.java_pid<pid> 发 load
                                   Attach Listener 线程收到
                                   → 加载 agent.jar
                                   → 调用 agentmain(args, inst)
    ← 返回
  之后:retransformClasses 让已加载类重新经过 transformer
text
类加载与转换链:
  ClassLoader.loadClass
    → 读取 class 字节
    → 依次调用所有 transformer.transform(...)
    → 得到最终 byte[]
    → defineClass → 校验(StackMapTable)→ 初始化
  任一步异常 → 类加载失败(NoClassDefFoundError / VerifyError)
text
retransform 生命周期:
  已加载类 C(旧字节码)
    → retransformClasses(C)
    → 从 C 的初始 classfile 重新跑所有 canRetransform 的 transformer
    → 得到新字节码 → 校验 → 替换方法体
  注意:已在执行的方法帧仍跑旧代码;新调用才用新代码
  • 版本/源码锚点:

    • JDK 5:java.lang.instrument、premain;JDK 6:agentmain + com.sun.tools.attach(Attach API)、retransformClasses;JDK 9:模块化,jdk.attach 模块,--add-opens;JDK 21:JEP 451 动态加载 agent 警告,-XX:+EnableDynamicAgentLoading。
    • Manifest 键:Premain-Class、Agent-Class、Can-Redefine-Classes、Can-Retransform-Classes、Boot-Class-Path;JVM 参数:-javaagent、-XX:+DisableAttachMechanism、-Djdk.attach.allowAttachSelf=true。
    • 字节码库:ASM 9.x(ClassReader/ClassWriter/ClassVisitor/AdviceAdapter)、ByteBuddy 1.14.x(AgentBuilder、Advice)、Javassist 3.29+。
    • 代表产品:Arthas 4.x(agentmain + ByteBuddy,watch/trace/jad)、SkyWalking 9.x(premain/agentmain + ByteBuddy 插件)、JaCoCo(on-the-fly transformer)、Mockito inline(byte-buddy-agent attach)、JVM-Sandbox(阿里,模块化 agent 框架)。
    • 相关:字节码增强与动态代理见 2.1-2;反射与 MethodHandle 见 2.1-1;Arthas/JFR 等诊断工具见 2.3-11;类加载与双亲委派见 2.3-2。
  • premain vs agentmain:

维度premainagentmain
触发JVM 启动,main 之前运行期 Attach
入口参数-javaagent:agent.jarVirtualMachine.loadAgent(...)
ManifestPremain-ClassAgent-Class
覆盖范围几乎所有类附加后加载的类 + retransform
典型用途APM、启动期增强Arthas、热修复、诊断
失败影响JVM 启动失败附加失败,目标 JVM 通常不受影响
  • 能改 / 不能改:
操作retransform / redefine
改方法体✅
改常量池、注解值(部分)✅
新增/删除字段❌
新增/删除方法❌
改方法签名❌
改继承/实现关系❌
改类名/包名❌
改正在执行的方法❌(旧栈帧继续旧代码)
  • 字节码库对比:
库API 层级性能典型使用者
ASM字节码指令级最高Arthas、JaCoCo、CGLib
ByteBuddy类型/方法级,友好高SkyWalking、Mockito
Javassist源码字符串级中老框架、简单增强
CGLib代理生成中Spring AOP(非 agent 场景)
  • 场景 → 实现:
场景实现方式
APM 链路追踪premain 注册 transformer,方法进出埋点
线上诊断(watch/trace)agentmain + retransform,按需增强
单测 Mockinline mock maker 用 agent 改字节码
代码覆盖率JaCoCo on-the-fly transformer
热修复agentmain + redefine/retransform(仅方法体)
安全 RASP启动期插桩关键 API(反序列化、命令执行)
  • 常见故障 → 根因 → 处理:
现象根因处理
Agent failed to startManifest 缺 Premain-Class补 Manifest
UnsupportedOperationException: class redefinition failed改了字段/签名/继承只改方法体
VerifyError: Expecting a stackmap frame未重算 StackMapTableASM COMPUTE_FRAMES 或 ByteBuddy
ClassCircularityErrortransformer 内加载类禁止在 transform 中加载类
NoClassDefFoundError(被增强类)agent 类不可见appendToBootstrapClassLoaderSearch
attach 失败权限/namespace/未开 attach同用户、同容器、检查参数
自附加失败默认禁止 self-attach-Djdk.attach.allowAttachSelf=true
JDK 21 警告JEP 451-XX:+EnableDynamicAgentLoading 或改启动期
热修复不生效方法已在栈上等待新调用/重启
多 agent 冲突transformer 顺序/重复增强明确顺序、幂等增强
内存泄漏transformer 持有 ClassLoader用弱引用、及时移除
  • 深挖点(面试官常追的 6 个):

    1. premain 和 agentmain 怎么选:能在启动参数里加 -javaagent 就选 premain——它在 main 前执行,能覆盖启动期加载的所有类(框架、连接池、序列化),适合 APM、RASP;不能重启、要临时诊断(Arthas、线上抓方法耗时)就用 agentmain + Attach,代价是只能对附加后加载的类生效,已加载的要 retransform,且受 attach 权限、容器 namespace、JDK 21 动态加载策略限制。
    2. Attach 到底怎么工作:外部进程用 VirtualMachine.attach(pid),在 Linux 上通过 /tmp/.java_pid<pid> 这个 Unix socket 与目标 JVM 的 Attach Listener 线程通信;发送 load agent.jar 后,目标 JVM 用系统类加载器加载 agent 并调用 agentmain。所以要求同用户、目标进程允许 attach(DisableAttachMechanism 关掉就不行)、容器里 PID namespace 一致;JDK 21 对动态加载 agent 加了警告,就是在收紧这条“任何进程都能往 JVM 里塞代码”的路径。
    3. retransform 为什么不能加字段:JVM 的类元数据(字段布局、方法表、vtable、对象大小)在类加载时就固定了,已经分配的对象按旧布局存在堆里;加字段会让所有存量对象“少一块内存”,JVM 无法安全迁移。所以规范只允许改方法体这类不影响布局的部分。retransform 还要从初始字节码重新跑 transformer,保证结果可重现;且已在栈上的帧不会回退重编译,热修复对“正在跑的方法”不立即生效。
    4. 栈映射帧为什么必须重算:Java 7+(class 版本 51)起,字节码校验器用 StackMapTable 做类型检查,而不是老式的数据流推导。你在方法体里插入了新指令,局部变量表和操作数栈的类型状态就变了,旧的帧不再匹配,校验器报 VerifyError。ASM 的 COMPUTE_FRAMES 会自动算,但它需要知道类的继承关系(getCommonSuperClass),默认实现用 Class.forName 可能加载错误类或触发 agent 递归,工程上要重写这个方法、用目标类的 ClassLoader 或只读字节码头。
    5. 类加载器和模块的坑:transformer 在 loadClass 的临界区里跑,里面不能 Class.forName 或加载新类,否则递归 transform,轻则 ClassCircularityError,重则死锁。被增强的类如果引用了 agent 的辅助类,要求这些类在同一个可见性范围——bootstrap 加载的类看不到 system classloader 的 agent 类,要用 appendToBootstrapClassLoaderSearch 把 agent 依赖塞进 bootstrap。JDK 9+ 后 java.base 的非导出包默认不可反射访问,agent 要用 --add-opens;用 Unsafe/sun.misc 的老 agent 在 JDK 17+ 会大面积失败。
    6. Agent 的性能与安全边界:transform 只在类加载/重转换时执行一次,本身开销可接受,但改写的代码会永久影响运行时(埋点过多会拖慢热点方法);retransform 会触发全量重跑 transformer 与校验,频繁调用有成本。安全上 agent 等于在目标 JVM 里执行任意代码,能力等同 RCE:生产要控制谁能 attach、agent 包要签名/白名单、避免加载来源不明的 agent;JDK 21 的警告就是对这条供应链风险的收敛。APM agent 还要注意多 agent 顺序与幂等增强,否则同一方法被增强两次。
  • 追问链:

    1. Java Agent 是什么? → JVMTI 的 Java 封装,字节码插桩。
    2. 两种入口? → premain / agentmain。
    3. premain 何时执行? → main 之前。
    4. 怎么触发 premain? → -javaagent。
    5. Manifest 要什么? → Premain-Class。
    6. agentmain 怎么触发? → Attach API。
    7. Attach 原理? → socket + Attach Listener。
    8. 为什么要权限? → 同用户/同 namespace。
    9. 能 attach 自己吗? → 需 allowAttachSelf。
    10. JDK 21 有什么变化? → 动态加载警告。
    11. Instrumentation 能干什么? → addTransformer/retransform。
    12. Transformer 返回什么? → null 或新字节码。
    13. retransform 和 redefine 区别? → 重跑 transformer vs 直接替换。
    14. 能加字段吗? → 不能。
    15. 能改方法体吗? → 能。
    16. 为什么不能加字段? → 对象布局已固定。
    17. 已执行的方法会变吗? → 不会,旧栈帧继续。
    18. 类加载时发生什么? → 读字节→transform→define→校验。
    19. transformer 里能加载类吗? → 不能,递归/死锁。
    20. ClassCircularityError? → 上面这条。
    21. NoClassDefFoundError? → agent 类不可见。
    22. 怎么解决? → appendToBootstrapClassLoaderSearch。
    23. 栈映射帧是什么? → Java 7+ 校验用的类型帧。
    24. 不重算会怎样? → VerifyError。
    25. ASM 怎么算? → COMPUTE_FRAMES。
    26. COMPUTE_FRAMES 的坑? → getCommonSuperClass 加载类。
    27. 常用字节码库? → ASM/ByteBuddy/Javassist。
    28. Arthas 原理? → agentmain + ByteBuddy。
    29. SkyWalking 原理? → agent + 插件增强。
    30. JaCoCo 原理? → on-the-fly transformer。
    31. Mockito inline? → byte-buddy-agent。
    32. 热修复能做到什么? → 只改方法体。
    33. 热修复为什么难? → 字段/签名不能改。
    34. 模块化影响? → add-opens、jdk.attach。
    35. JDK 17 老 agent 为什么挂? → 强封装。
    36. agent 性能开销? → transform 一次,改写代码长期影响。
    37. retransform 开销? → 重跑链 + 校验。
    38. 多 agent 冲突? → 顺序与幂等。
    39. agent 内存泄漏? → transformer 持有 ClassLoader。
    40. agent 安全风险? → 等同 RCE。
    41. 怎么防? → 权限、签名、白名单。
    42. 容器里 attach? → PID namespace/权限。
    43. attach 失败怎么查? → 日志、socket、参数。
    44. agent 能改 JDK 类吗? → 能,但要注意 bootstrap 可见性。
    45. instrument 和 JVMTI 关系? → Java 封装。
    46. 能拿到对象大小吗? → getObjectSize。
    47. 能统计类加载吗? → getAllLoadedClasses。
    48. 生产怎么用 agent? → APM/诊断/安全,可控可观测。
    49. 什么时候不该用? → 能改代码就别热修。
    50. 一句话总结? → 两个入口、一个 transformer、三条边界(方法体/帧/类加载器)。
  • 生产案例/取舍(示例,替换成你的项目):

    • Arthas attach 容器内 JVM 失败,定位为 PID namespace 与权限;改在容器内执行。
    • 自研 agent 在 JDK 21 打印动态加载警告;改启动期 -javaagent 或加参数。
    • transformer 里 Class.forName 触发 ClassCircularityError;改为只读字节码头、延迟加载。
    • ASM 忘记 COMPUTE_FRAMES,注入后 VerifyError;补帧计算并重写 getCommonSuperClass。
    • 热修复上线后老请求仍走旧逻辑;确认是栈上方法帧,改为等待新调用 + 重启兜底。
    • agent 依赖放在 system classloader,bootstrap 类引用报 NoClassDefFoundError;appendToBootstrapClassLoaderSearch。
    • JDK 17 升级后老 agent 反射 java.base 失败;补 --add-opens 并替换 Unsafe 用法。
    • SkyWalking 与自研 agent 同时增强同一方法,耗时翻倍;统一增强入口、做幂等判断。
    • agent 持有业务 ClassLoader 导致 Metaspace 泄漏;改弱引用并在卸载时移除 transformer。
    • 测试环境 Mockito inline 与 JaCoCo 同时插桩,类校验失败;调整 agent 顺序。
    • 生产误加载 debug agent,热点方法埋点过多,P99 上升 15%;改为采样与开关。
    • 取舍:premain 换覆盖全面,代价是必须重启;agentmain 换灵活,代价是覆盖不全与权限限制;ASM 换性能,代价是开发成本;ByteBuddy 换效率,代价是抽象层开销;热修复换快速止血,代价是只能改方法体、易掩盖根因。
  • 易错点:

    • 认为 Agent 能随便改类结构。
    • 认为 agentmain 能改所有已加载类。
    • 认为 retransform 是在上次结果上叠加。
    • 认为热修复对正在执行的方法立即生效。
    • 认为加了字段也能 redefine。
    • 认为 transformer 里可以自由加载类。
    • 认为 StackMapTable 可省略。
    • 认为 COMPUTE_FRAMES 没有副作用。
    • 认为 agent 类一定对目标类可见。
    • 认为 attach 不需要权限。
    • 认为容器里 attach 和宿主机一样。
    • 认为 JDK 21 还能无警告动态加载。
    • 认为 premain 失败不影响启动。
    • 认为 agentmain 失败会拖垮目标 JVM。
    • 认为 redefineClasses 和 retransformClasses 等价。
    • 认为 transformer 只会被调用一次。
    • 认为 agent 没有性能开销。
    • 认为 agent 没有安全风险。
    • 认为多 agent 不会冲突。
    • 认为 agent 不会泄漏 ClassLoader。
    • 认为 Arthas 是 JDK 自带工具。
    • 认为 JaCoCo 只能离线插桩。
    • 认为 Mockito 不需要 agent。
    • 认为 JVMTI 和 Instrumentation 是一回事。
    • 认为 bootstrap 类能直接引用 agent 类。
    • 认为 JDK 9 模块化对 agent 没影响。
    • 认为 -javaagent 可以加载多个(其实可以,但要注意顺序)。
    • 认为 agent 只能用于监控。
    • 认为热修复是银弹。
    • 认为线上 attach 没有审计要求。
  • 30 秒口述稿:

Java Agent 是 JVM 提供的字节码插桩入口。启动时用 -javaagent 走 premain,在 main 之前拿到 Instrumentation,注册 ClassFileTransformer;运行期用 Attach API 走 agentmain,通过 socket 连到目标 JVM 的 Attach Listener,加载 agent 后再 retransform 已加载的类。Transformer 在类定义之前改写字节码,常用 ASM 或 ByteBuddy,改方法体时必须重算 StackMapTable,否则校验不过。它的边界很清楚:只能改方法体,不能加字段、改签名、改继承;已经在栈上的方法还是跑旧代码;transformer 在类加载关键路径上,不能在里面加载类,还要注意 bootstrap 可见性和 JDK 9 之后的模块开放。APM、Arthas、JaCoCo、Mockito 都是这套机制。

  • 3 分钟展开顺序:结论(两个入口 + 一个 transformer + 三条边界)→ JVMTI 与 Instrumentation 的关系 → premain 的 Manifest 与启动流程 → agentmain 的 Attach 机制与权限 → Instrumentation API 与 transformer 返回值 → 字节码改写与 StackMapTable → retransform 的语义与"不能加字段"的原因 → 类加载器/模块的坑 → 典型产品(Arthas/SkyWalking/JaCoCo/Mockito)→ 性能、安全与生产实践。