Appearance
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、热修复都建在这套机制上。分层要点:
- 定位:JVM 的 JVMTI 是 C 层调试/监控接口,
java.lang.instrument是它在 Java 层的封装(JDK 5 引入)。Agent 是一段随目标 JVM 运行的代码,通过Instrumentation在类加载链路里插入自己,从而做监控、增强、Mock、热更新。 - 两种入口: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。 - premain 的装载条件:agent jar 的
META-INF/MANIFEST.MF必须写Premain-Class;需要重定义/重转换时写Can-Redefine-Classes: true、Can-Retransform-Classes: true;Boot-Class-Path可把依赖加进 bootstrap 搜索路径。premain抛异常会导致 JVM 启动失败。 - 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 要注意)。 - Instrumentation 能做什么:
addTransformer(t, canRetransform)注册转换器;retransformClasses(...)对已加载类重跑转换;redefineClasses(...)直接替换类定义;getAllLoadedClasses()、isModifiableClass()、getObjectSize()、appendToBootstrapClassLoaderSearch(JarFile)、appendToSystemClassLoaderSearch(JarFile)。Transformer 的返回值:null表示不改,返回byte[]表示用新字节码替换。 - 字节码改写:主流用 ASM(访问者/树 API,性能最好、最底层)、ByteBuddy(API 友好,Arthas/Mockito/SkyWalking 常用)、Javassist(源码级 API,性能一般)、CGLib(已较少用于 agent)。改写方法体要做 try/finally、计时、异常捕获时,必须重算
StackMapTable(ASMClassWriter.COMPUTE_FRAMES),否则 Java 7+ 校验器直接拒绝;而计算帧需要类型层次,getCommonSuperClass用错类加载器会触发类加载甚至ClassCircularityError。 - retransform 的边界:只能改方法体(以及常量池等),不能新增/删除字段或方法、不能改方法签名、不能改继承关系;
redefineClasses限制更严。retransform的语义是从初始 classfile 重新应用所有canRetransform=true的 transformer,不是在上次结果上叠加;已经在栈上的方法帧继续执行旧版本,新调用才走新代码——所以“热修复”对正在执行的方法不是立即生效。isModifiableClass为 false 的类(部分数组、基本类型、hidden class)不能改。 - 类加载器与模块:transformer 运行在类加载的关键路径上,不能在里面加载类(会递归触发 transform,导致死锁或
ClassCircularityError);被增强的类若引用 agent 的类,而 agent 不在其可见的类加载器里,会NoClassDefFoundError,需要appendToBootstrapClassLoaderSearch或把依赖放进 bootstrap。JDK 9+ 模块化后,访问java.base的非导出包要--add-opens;JDK 21 起动态加载 agent 会打印警告(JEP 451),需要-XX:+EnableDynamicAgentLoading才静默,未来版本可能默认禁止。
- 定位:JVM 的 JVMTI 是 C 层调试/监控接口,
图/流程:
text
premain(启动期):
java -javaagent:agent.jar=opts -jar app.jar
→ JVM 解析 Manifest 的 Premain-Class
→ 加载 agent → 调用 premain(args, inst)
→ agent 注册 ClassFileTransformer
→ main 开始执行;此后每个类加载都经过 transformertext
agentmain(运行期 Attach):
外部进程 目标 JVM
VirtualMachine.attach(pid)
→ 通过 /tmp/.java_pid<pid> 发 load
Attach Listener 线程收到
→ 加载 agent.jar
→ 调用 agentmain(args, inst)
← 返回
之后:retransformClasses 让已加载类重新经过 transformertext
类加载与转换链:
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。
- JDK 5:
premain vs agentmain:
| 维度 | premain | agentmain |
|---|---|---|
| 触发 | JVM 启动,main 之前 | 运行期 Attach |
| 入口参数 | -javaagent:agent.jar | VirtualMachine.loadAgent(...) |
| Manifest | Premain-Class | Agent-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,按需增强 |
| 单测 Mock | inline mock maker 用 agent 改字节码 |
| 代码覆盖率 | JaCoCo on-the-fly transformer |
| 热修复 | agentmain + redefine/retransform(仅方法体) |
| 安全 RASP | 启动期插桩关键 API(反序列化、命令执行) |
- 常见故障 → 根因 → 处理:
| 现象 | 根因 | 处理 |
|---|---|---|
Agent failed to start | Manifest 缺 Premain-Class | 补 Manifest |
UnsupportedOperationException: class redefinition failed | 改了字段/签名/继承 | 只改方法体 |
VerifyError: Expecting a stackmap frame | 未重算 StackMapTable | ASM COMPUTE_FRAMES 或 ByteBuddy |
ClassCircularityError | transformer 内加载类 | 禁止在 transform 中加载类 |
NoClassDefFoundError(被增强类) | agent 类不可见 | appendToBootstrapClassLoaderSearch |
| attach 失败 | 权限/namespace/未开 attach | 同用户、同容器、检查参数 |
| 自附加失败 | 默认禁止 self-attach | -Djdk.attach.allowAttachSelf=true |
| JDK 21 警告 | JEP 451 | -XX:+EnableDynamicAgentLoading 或改启动期 |
| 热修复不生效 | 方法已在栈上 | 等待新调用/重启 |
| 多 agent 冲突 | transformer 顺序/重复增强 | 明确顺序、幂等增强 |
| 内存泄漏 | transformer 持有 ClassLoader | 用弱引用、及时移除 |
深挖点(面试官常追的 6 个):
- premain 和 agentmain 怎么选:能在启动参数里加
-javaagent就选premain——它在main前执行,能覆盖启动期加载的所有类(框架、连接池、序列化),适合 APM、RASP;不能重启、要临时诊断(Arthas、线上抓方法耗时)就用agentmain+ Attach,代价是只能对附加后加载的类生效,已加载的要retransform,且受 attach 权限、容器 namespace、JDK 21 动态加载策略限制。 - 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 里塞代码”的路径。 - retransform 为什么不能加字段:JVM 的类元数据(字段布局、方法表、vtable、对象大小)在类加载时就固定了,已经分配的对象按旧布局存在堆里;加字段会让所有存量对象“少一块内存”,JVM 无法安全迁移。所以规范只允许改方法体这类不影响布局的部分。
retransform还要从初始字节码重新跑 transformer,保证结果可重现;且已在栈上的帧不会回退重编译,热修复对“正在跑的方法”不立即生效。 - 栈映射帧为什么必须重算:Java 7+(class 版本 51)起,字节码校验器用
StackMapTable做类型检查,而不是老式的数据流推导。你在方法体里插入了新指令,局部变量表和操作数栈的类型状态就变了,旧的帧不再匹配,校验器报VerifyError。ASM 的COMPUTE_FRAMES会自动算,但它需要知道类的继承关系(getCommonSuperClass),默认实现用Class.forName可能加载错误类或触发 agent 递归,工程上要重写这个方法、用目标类的 ClassLoader 或只读字节码头。 - 类加载器和模块的坑: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+ 会大面积失败。 - Agent 的性能与安全边界:
transform只在类加载/重转换时执行一次,本身开销可接受,但改写的代码会永久影响运行时(埋点过多会拖慢热点方法);retransform会触发全量重跑 transformer 与校验,频繁调用有成本。安全上 agent 等于在目标 JVM 里执行任意代码,能力等同 RCE:生产要控制谁能 attach、agent 包要签名/白名单、避免加载来源不明的 agent;JDK 21 的警告就是对这条供应链风险的收敛。APM agent 还要注意多 agent 顺序与幂等增强,否则同一方法被增强两次。
- premain 和 agentmain 怎么选:能在启动参数里加
追问链:
- Java Agent 是什么? → JVMTI 的 Java 封装,字节码插桩。
- 两种入口? → premain / agentmain。
- premain 何时执行? → main 之前。
- 怎么触发 premain? →
-javaagent。 - Manifest 要什么? →
Premain-Class。 - agentmain 怎么触发? → Attach API。
- Attach 原理? → socket + Attach Listener。
- 为什么要权限? → 同用户/同 namespace。
- 能 attach 自己吗? → 需
allowAttachSelf。 - JDK 21 有什么变化? → 动态加载警告。
- Instrumentation 能干什么? → addTransformer/retransform。
- Transformer 返回什么? → null 或新字节码。
- retransform 和 redefine 区别? → 重跑 transformer vs 直接替换。
- 能加字段吗? → 不能。
- 能改方法体吗? → 能。
- 为什么不能加字段? → 对象布局已固定。
- 已执行的方法会变吗? → 不会,旧栈帧继续。
- 类加载时发生什么? → 读字节→transform→define→校验。
- transformer 里能加载类吗? → 不能,递归/死锁。
- ClassCircularityError? → 上面这条。
- NoClassDefFoundError? → agent 类不可见。
- 怎么解决? → appendToBootstrapClassLoaderSearch。
- 栈映射帧是什么? → Java 7+ 校验用的类型帧。
- 不重算会怎样? → VerifyError。
- ASM 怎么算? → COMPUTE_FRAMES。
- COMPUTE_FRAMES 的坑? → getCommonSuperClass 加载类。
- 常用字节码库? → ASM/ByteBuddy/Javassist。
- Arthas 原理? → agentmain + ByteBuddy。
- SkyWalking 原理? → agent + 插件增强。
- JaCoCo 原理? → on-the-fly transformer。
- Mockito inline? → byte-buddy-agent。
- 热修复能做到什么? → 只改方法体。
- 热修复为什么难? → 字段/签名不能改。
- 模块化影响? → add-opens、jdk.attach。
- JDK 17 老 agent 为什么挂? → 强封装。
- agent 性能开销? → transform 一次,改写代码长期影响。
- retransform 开销? → 重跑链 + 校验。
- 多 agent 冲突? → 顺序与幂等。
- agent 内存泄漏? → transformer 持有 ClassLoader。
- agent 安全风险? → 等同 RCE。
- 怎么防? → 权限、签名、白名单。
- 容器里 attach? → PID namespace/权限。
- attach 失败怎么查? → 日志、socket、参数。
- agent 能改 JDK 类吗? → 能,但要注意 bootstrap 可见性。
- instrument 和 JVMTI 关系? → Java 封装。
- 能拿到对象大小吗? → getObjectSize。
- 能统计类加载吗? → getAllLoadedClasses。
- 生产怎么用 agent? → APM/诊断/安全,可控可观测。
- 什么时候不该用? → 能改代码就别热修。
- 一句话总结? → 两个入口、一个 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)→ 性能、安全与生产实践。